<?php
/**
 * CSort class file.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @link http://www.yiiframework.com/
 * @copyright 2008-2013 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

/**
 * CSort represents information relevant to sorting.
 *
 * When data needs to be sorted according to one or several attributes,
 * we can use CSort to represent the sorting information and generate
 * appropriate hyperlinks that can lead to sort actions.
 *
 * CSort is designed to be used together with {@link CActiveRecord}.
 * When creating a CSort instance, you need to specify {@link modelClass}.
 * You can use CSort to generate hyperlinks by calling {@link link}.
 * You can also use CSort to modify a {@link CDbCriteria} instance by calling {@link applyOrder} so that
 * it can cause the query results to be sorted according to the specified
 * attributes.
 *
 * In order to prevent SQL injection attacks, CSort ensures that only valid model attributes
 * can be sorted. This is determined based on {@link modelClass} and {@link attributes}.
 * When {@link attributes} is not set, all attributes belonging to {@link modelClass}
 * can be sorted. When {@link attributes} is set, only those attributes declared in the property
 * can be sorted.
 *
 * By configuring {@link attributes}, one can perform more complex sorts that may
 * consist of things like compound attributes (e.g. sort based on the combination of
 * first name and last name of users).
 *
 * The property {@link attributes} should be an array of key-value pairs, where the keys
 * represent the attribute names, while the values represent the virtual attribute definitions.
 * For more details, please check the documentation about {@link attributes}.
 *
 * @property string $orderBy The order-by columns represented by this sort object.
 * This can be put in the ORDER BY clause of a SQL statement.
 * @property array $directions Sort directions indexed by attribute names.
 * The sort direction. Can be either CSort::SORT_ASC for ascending order or
 * CSort::SORT_DESC for descending order.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @package system.web
 */
class CSort extends CComponent
{
    /**
     * Sort ascending
     * @since 1.1.10
     */
    const SORT_ASC = false;

    /**
     * Sort descending
     * @since 1.1.10
     */
    const SORT_DESC = true;

    /**
     * @var boolean whether the sorting can be applied to multiple attributes simultaneously.
     * Defaults to false, which means each time the data can only be sorted by one attribute.
     */
    public $multiSort = false;
    /**
     * @var string the name of the model class whose attributes can be sorted.
     * The model class must be a child class of {@link CActiveRecord}.
     */
    public $modelClass;
    /**
     * @var array list of attributes that are allowed to be sorted.
     * For example, array('user_id','create_time') would specify that only 'user_id'
     * and 'create_time' of the model {@link modelClass} can be sorted.
     * By default, this property is an empty array, which means all attributes in
     * {@link modelClass} are allowed to be sorted.
     *
     * This property can also be used to specify complex sorting. To do so,
     * a virtual attribute can be declared in terms of a key-value pair in the array.
     * The key refers to the name of the virtual attribute that may appear in the sort request,
     * while the value specifies the definition of the virtual attribute.
     *
     * In the simple case, a key-value pair can be like <code>'user'=>'user_id'</code>
     * where 'user' is the name of the virtual attribute while 'user_id' means the virtual
     * attribute is the 'user_id' attribute in the {@link modelClass}.
     *
     * A more flexible way is to specify the key-value pair as
     * <pre>
     * 'user'=>array(
     *     'asc'=>'first_name, last_name',
     *     'desc'=>'first_name DESC, last_name DESC',
     *     'label'=>'Name'
     * )
     * </pre>
     * where 'user' is the name of the virtual attribute that specifies the full name of user
     * (a compound attribute consisting of first name and last name of user). In this case,
     * we have to use an array to define the virtual attribute with three elements: 'asc',
     * 'desc' and 'label'.
     *
     * The above approach can also be used to declare virtual attributes that consist of relational
     * attributes. For example,
     * <pre>
     * 'price'=>array(
     *     'asc'=>'item.price',
     *     'desc'=>'item.price DESC',
     *     'label'=>'Item Price'
     * )
     * </pre>
     *
     * Note, the attribute name should not contain '-' or '.' characters because
     * they are used as {@link separators}.
     *
     * Starting from version 1.1.3, an additional option named 'default' can be used in the virtual attribute
     * declaration. This option specifies whether an attribute should be sorted in ascending or descending
     * order upon user clicking the corresponding sort hyperlink if it is not currently sorted. The valid
     * option values include 'asc' (default) and 'desc'. For example,
     * <pre>
     * 'price'=>array(
     *     'asc'=>'item.price',
     *     'desc'=>'item.price DESC',
     *     'label'=>'Item Price',
     *     'default'=>'desc',
     * )
     * </pre>
     *
     * Also starting from version 1.1.3, you can include a star ('*') element in this property so that
     * all model attributes are available for sorting, in addition to those virtual attributes. For example,
     * <pre>
     * 'attributes'=>array(
     *     'price'=>array(
     *         'asc'=>'item.price',
     *         'desc'=>'item.price DESC',
     *         'label'=>'Item Price',
     *         'default'=>'desc',
     *     ),
     *     '*',
     * )
     * </pre>
     * Note that when a name appears as both a model attribute and a virtual attribute, the position of
     * the star element in the array determines which one takes precedence. In particular, if the star
     * element is the first element in the array, the model attribute takes precedence; and if the star
     * element is the last one, the virtual attribute takes precedence.
     */
    public $attributes = array();
    /**
     * @var string the name of the GET parameter that specifies which attributes to be sorted
     * in which direction. Defaults to 'sort'.
     */
    public $sortVar = 'sort';
    /**
     * @var string the tag appeared in the GET parameter that indicates the attribute should be sorted
     * in descending order. Defaults to 'desc'.
     */
    public $descTag = 'desc';
    /**
     * @var mixed the default order that should be applied to the query criteria when
     * the current request does not specify any sort. For example, 'name, create_time DESC' or
     * 'UPPER(name)'.
     *
     * Starting from version 1.1.3, you can also specify the default order using an array.
     * The array keys could be attribute names or virtual attribute names as declared in {@link attributes},
     * and the array values indicate whether the sorting of the corresponding attributes should
     * be in descending order. For example,
     * <pre>
     * 'defaultOrder'=>array(
     *     'price'=>CSort::SORT_DESC,
     * )
     * </pre>
     * `SORT_DESC` and `SORT_ASC` are available since 1.1.10. In earlier Yii versions you should use
     * `true` and `false` respectively.
     *
     * Please note when using array to specify the default order, the corresponding attributes
     * will be put into {@link directions} and thus affect how the sort links are rendered
     * (e.g. an arrow may be displayed next to the currently active sort link).
     */
    public $defaultOrder;
    /**
     * @var string the route (controller ID and action ID) for generating the sorted contents.
     * Defaults to empty string, meaning using the currently requested route.
     */
    public $route = '';
    /**
     * @var array separators used in the generated URL. This must be an array consisting of
     * two elements. The first element specifies the character separating different
     * attributes, while the second element specifies the character separating attribute name
     * and the corresponding sort direction. Defaults to array('-','.').
     */
    public $separators = array('-', '.');
    /**
     * @var array the additional GET parameters (name=>value) that should be used when generating sort URLs.
     * Defaults to null, meaning using the currently available GET parameters.
     */
    public $params;

    private $_directions;

    /**
     * Constructor.
     * @param string $modelClass the class name of data models that need to be sorted.
     * This should be a child class of {@link CActiveRecord}.
     */
    public function __construct($modelClass = null)
    {
        $this->modelClass = $modelClass;
    }

    /**
     * Modifies the query criteria by changing its {@link CDbCriteria::order} property.
     * This method will use {@link directions} to determine which columns need to be sorted.
     * They will be put in the ORDER BY clause. If the criteria already has non-empty {@link CDbCriteria::order} value,
     * the new value will be appended to it.
     * @param CDbCriteria $criteria the query criteria
     */
    public function applyOrder($criteria)
    {
        $order = $this->getOrderBy($criteria);
        if (!empty($order)) {
            if (!empty($criteria->order))
                $criteria->order .= ', ';
            $criteria->order .= $order;
        }
    }

    /**
     * @param CDbCriteria $criteria the query criteria
     * @return string the order-by columns represented by this sort object.
     * This can be put in the ORDER BY clause of a SQL statement.
     * @since 1.1.0
     */
    public function getOrderBy($criteria = null)
    {
        $directions = $this->getDirections();
        if (empty($directions))
            return is_string($this->defaultOrder) ? $this->defaultOrder : '';
        else {
            if ($this->modelClass !== null)
                $schema = $this->getModel($this->modelClass)->getDbConnection()->getSchema();
            $orders = array();
            foreach ($directions as $attribute => $descending) {
                $definition = $this->resolveAttribute($attribute);
                if (is_array($definition)) {
                    if ($descending)
                        $orders[] = isset($definition['desc']) ? $definition['desc'] : $attribute . ' DESC';
                    else
                        $orders[] = isset($definition['asc']) ? $definition['asc'] : $attribute;
                } elseif ($definition !== false) {
                    $attribute = $definition;
                    if (isset($schema)) {
                        if (($pos = strpos($attribute, '.')) !== false)
                            $attribute = $schema->quoteTableName(substr($attribute, 0, $pos)) . '.' . $schema->quoteColumnName(substr($attribute, $pos + 1));
                        else
                            $attribute = ($criteria === null || $criteria->alias === null ? $this->getModel($this->modelClass)->getTableAlias(true) : $schema->quoteTableName($criteria->alias)) . '.' . $schema->quoteColumnName($attribute);
                    }
                    $orders[] = $descending ? $attribute . ' DESC' : $attribute;
                }
            }
            return implode(', ', $orders);
        }
    }

    /**
     * Generates a hyperlink that can be clicked to cause sorting.
     * @param string $attribute the attribute name. This must be the actual attribute name, not alias.
     * If it is an attribute of a related AR object, the name should be prefixed with
     * the relation name (e.g. 'author.name', where 'author' is the relation name).
     * @param string $label the link label. If null, the label will be determined according
     * to the attribute (see {@link resolveLabel}).
     * @param array $htmlOptions additional HTML attributes for the hyperlink tag
     * @return string the generated hyperlink
     */
    public function link($attribute, $label = null, $htmlOptions = array())
    {
        if ($label === null)
            $label = $this->resolveLabel($attribute);
        if (($definition = $this->resolveAttribute($attribute)) === false)
            return $label;
        $directions = $this->getDirections();
        if (isset($directions[$attribute])) {
            $class = $directions[$attribute] ? 'desc' : 'asc';
            if (isset($htmlOptions['class']))
                $htmlOptions['class'] .= ' ' . $class;
            else
                $htmlOptions['class'] = $class;
            $descending = !$directions[$attribute];
            unset($directions[$attribute]);
        } elseif (is_array($definition) && isset($definition['default']))
            $descending = $definition['default'] === 'desc';
        else
            $descending = false;

        if ($this->multiSort)
            $directions = array_merge(array($attribute => $descending), $directions);
        else
            $directions = array($attribute => $descending);

        $url = $this->createUrl(Yii::app()->getController(), $directions);

        return $this->createLink($attribute, $label, $url, $htmlOptions);
    }

    /**
     * Resolves the attribute label for the specified attribute.
     * This will invoke {@link CActiveRecord::getAttributeLabel} to determine what label to use.
     * If the attribute refers to a virtual attribute declared in {@link attributes},
     * then the label given in the {@link attributes} will be returned instead.
     * @param string $attribute the attribute name.
     * @return string the attribute label
     */
    public function resolveLabel($attribute)
    {
        $definition = $this->resolveAttribute($attribute);
        if (is_array($definition)) {
            if (isset($definition['label']))
                return $definition['label'];
        } elseif (is_string($definition))
            $attribute = $definition;
        if ($this->modelClass !== null)
            return $this->getModel($this->modelClass)->getAttributeLabel($attribute);
        else
            return $attribute;
    }

    /**
     * Returns the currently requested sort information.
     * @return array sort directions indexed by attribute names.
     * Sort direction can be either CSort::SORT_ASC for ascending order or
     * CSort::SORT_DESC for descending order.
     */
    public function getDirections()
    {
        if ($this->_directions === null) {
            $this->_directions = array();
            if (isset($_GET[$this->sortVar]) && is_string($_GET[$this->sortVar])) {
                $attributes = explode($this->separators[0], $_GET[$this->sortVar]);
                foreach ($attributes as $attribute) {
                    if (($pos = strrpos($attribute, $this->separators[1])) !== false) {
                        $descending = substr($attribute, $pos + 1) === $this->descTag;
                        if ($descending)
                            $attribute = substr($attribute, 0, $pos);
                    } else
                        $descending = false;

                    if (($this->resolveAttribute($attribute)) !== false) {
                        $this->_directions[$attribute] = $descending;
                        if (!$this->multiSort)
                            return $this->_directions;
                    }
                }
            }
            if ($this->_directions === array() && is_array($this->defaultOrder))
                $this->_directions = $this->defaultOrder;
        }
        return $this->_directions;
    }

    /**
     * Returns the sort direction of the specified attribute in the current request.
     * @param string $attribute the attribute name
     * @return mixed Sort direction of the attribute. Can be either CSort::SORT_ASC
     * for ascending order or CSort::SORT_DESC for descending order. Value is null
     * if the attribute doesn't need to be sorted.
     */
    public function getDirection($attribute)
    {
        $this->getDirections();
        return isset($this->_directions[$attribute]) ? $this->_directions[$attribute] : null;
    }

    /**
     * Creates a URL that can lead to generating sorted data.
     * @param CController $controller the controller that will be used to create the URL.
     * @param array $directions the sort directions indexed by attribute names.
     * The sort direction can be either CSort::SORT_ASC for ascending order or
     * CSort::SORT_DESC for descending order.
     * @return string the URL for sorting
     */
    public function createUrl($controller, $directions)
    {
        $sorts = array();
        foreach ($directions as $attribute => $descending)
            $sorts[] = $descending ? $attribute . $this->separators[1] . $this->descTag : $attribute;
        $params = $this->params === null ? $_GET : $this->params;
        $params[$this->sortVar] = implode($this->separators[0], $sorts);
        return $controller->createUrl($this->route, $params);
    }

    /**
     * Returns the real definition of an attribute given its name.
     *
     * The resolution is based on {@link attributes} and {@link CActiveRecord::attributeNames}.
     * <ul>
     * <li>When {@link attributes} is an empty array, if the name refers to an attribute of {@link modelClass},
     * then the name is returned back.</li>
     * <li>When {@link attributes} is not empty, if the name refers to an attribute declared in {@link attributes},
     * then the corresponding virtual attribute definition is returned. Starting from version 1.1.3, if {@link attributes}
     * contains a star ('*') element, the name will also be used to match against all model attributes.</li>
     * <li>In all other cases, false is returned, meaning the name does not refer to a valid attribute.</li>
     * </ul>
     * @param string $attribute the attribute name that the user requests to sort on
     * @return mixed the attribute name or the virtual attribute definition. False if the attribute cannot be sorted.
     */
    public function resolveAttribute($attribute)
    {
        if ($this->attributes !== array())
            $attributes = $this->attributes;
        elseif ($this->modelClass !== null)
            $attributes = $this->getModel($this->modelClass)->attributeNames();
        else
            return false;
        foreach ($attributes as $name => $definition) {
            if (is_string($name)) {
                if ($name === $attribute)
                    return $definition;
            } elseif ($definition === '*') {
                if ($this->modelClass !== null && $this->getModel($this->modelClass)->hasAttribute($attribute))
                    return $attribute;
            } elseif ($definition === $attribute)
                return $attribute;
        }
        return false;
    }

    /**
     * Given active record class name returns new model instance.
     *
     * @param string $className active record class name.
     * @return CActiveRecord active record model instance.
     *
     * @since 1.1.14
     */
    protected function getModel($className)
    {
        return CActiveRecord::model($className);
    }

    /**
     * Creates a hyperlink based on the given label and URL.
     * You may override this method to customize the link generation.
     * @param string $attribute the name of the attribute that this link is for
     * @param string $label the label of the hyperlink
     * @param string $url the URL
     * @param array $htmlOptions additional HTML options
     * @return string the generated hyperlink
     */
    protected function createLink($attribute, $label, $url, $htmlOptions)
    {
        return CHtml::link($label, $url, $htmlOptions);
    }
}